//
//  ZegoUIKitEvent.swift
//  ZegoUIKit
//
//  事件处理核心协议 - 定义ZegoUIKit所有关键事件回调
//  注意：所有回调方法默认在主线程触发
//  Created by zego on 2022/7/25
//

import UIKit
import ZegoExpressEngine

@objc public protocol ZegoUIKitEventHandle: AnyObject {
    //MARK: - user 用户状态事件
    
    /// 远程用户加入房间（首次加入或断线重连后加入）
    /// - 触发时机: 新用户加入或用户列表刷新时
    /// - 典型应用: 更新用户列表UI、播放加入音效
    @objc optional func onRemoteUserJoin(_ userList:[ZegoUIKitUser])
    
    /// 远程用户离开房间（主动退出或连接断开）
    /// - 参数userList: 离开的用户对象数组
    /// - 典型应用: 更新用户列表、显示离开通知
    @objc optional func onRemoteUserLeave(_ userList:[ZegoUIKitUser])
    
    /// 房间内只剩当前用户时触发
    /// - 典型应用: 展示空状态UI、自动关闭房间
    @objc optional func onOnlySelfInRoom(_ userList:[ZegoUIKitUser])
    
    /// 用户数量或属性发生变化（如角色变更、名称修改）
    /// - 触发时机: 每30秒同步或手动刷新用户列表
    /// - 注意: userList为nil表示全量更新
    @objc optional func onUserCountOrPropertyChanged(_ userList:[ZegoUIKitUser]?)
    
    // MARK: - room 房间状态事件
    /// 房间状态变化（连接中/已连接/断开等）
    /// - 参数reason: 状态变化原因（网络切换、主动操作等）
    /// - 参数errorCode: 错误码（参考ZegoErrorCode）
    /// - 典型应用: 显示连接状态提示、重连逻辑
    @objc optional func onRoomStateChanged(_ reason: ZegoUIKitRoomStateChangedReason, errorCode: Int32, extendedData: [AnyHashable : Any], roomID: String)
    
    /// 单个房间属性更新（键值对变更）
    /// - 典型应用: 同步房间主题、密码等设置
    @objc optional func onRoomPropertyUpdated(_ key: String, oldValue: String, newValue: String)
    
    /// 全量房间属性更新（批量更新时触发）
    @objc optional func onRoomPropertiesFullUpdated(_ updateKeys: [String], oldProperties: [String : String], properties: [String : String])
    
    
    // MARK: - audio video音视频事件
    /// 用户摄像头状态变化
    /// - 注意: 包含本地用户和远程用户
    @objc optional func onCameraOn(_ user: ZegoUIKitUser, isOn: Bool)
    
    /// 用户麦克风状态变化
    /// - 典型应用: 显示麦克风图标状态
    @objc optional func onMicrophoneOn(_ user: ZegoUIKitUser, isOn: Bool)
    
    /// 远端用户音量等级更新（用于显示声波动画）
    @objc optional func onSoundLevelUpdate(_ userInfo: ZegoUIKitUser, level: Double)
    
    /// 本地采集音量信息（高级音频处理场景）
    @objc optional func onCapturedSoundLevelInfoUpdate(_ soundLevelInfo: ZegoSoundLevelInfo)
    
    /// 所有远端用户音量信息（语音突显功能）
    @objc optional func onRemoteSoundLevelInfoUpdate(_ soundLevelInfos:[String: ZegoSoundLevelInfo])
    
    /// 音视频流可用通知（首帧渲染就绪）
    @objc optional func onAudioVideoAvailable(_ userList: [ZegoUIKitUser])
    
    /// 音视频流不可用（连接中断或主动关闭）
    @objc optional func onAudioVideoUnavailable(_ userList: [ZegoUIKitUser])
    
    /// 屏幕共享流可用
    @objc optional func onScreenSharingAvailable(_ userList: [ZegoUIKitUser])
    
    /// 屏幕共享流不可用
    @objc optional func onScreenSharingUnavailable(_ userList: [ZegoUIKitUser])
    
    /// 音频输出设备变化（扬声器/听筒/耳机切换）
    @objc optional func onAudioOutputDeviceChanged(_ audioOutput: ZegoUIKitAudioOutputDevice)
    
    /// 接收到SEI数据（同步附加信息，如歌词时间戳）
    @objc optional func onPlayerRecvSEI(_ seiString: String, streamID: String)
    
    /// 音频首帧接收（可在此隐藏加载动画）
    @objc optional func onPlayerRecvAudioFirstFrame(_ streamID: String)
    
    /// 视频首帧接收（重要性能指标）
    @objc optional func onPlayerRecvVideoFirstFrame(_ streamID: String)
    
    /// 开始拉流后的回调（统计拉流成功率）
    @objc optional func onAfterStartPlayStream(_ streamID: String,  channel: ZegoPublishChannel)
    
    
    //MARK: - room message 房间消息事件
    /// 收到房间消息（文字/表情等）
    /// - 注意: 消息已通过敏感词过滤
    @objc optional func onInRoomMessageReceived(_ messageList: [ZegoInRoomMessage])
    
    /// 消息发送状态变化（发送中/成功/失败）
    @objc optional func onInRoomMessageSendingStateChanged(_ message: ZegoInRoomMessage)
    //MARK: 内部事件处理不对外回调
    /// 接收自定义命令（内部事件，不对外暴露）
    @objc optional func onInRoomCommandReceived(_ fromUser: ZegoUIKitUser, command: String)
    //MARK: 业务层用户监听，过滤了内部的事件。
    /// 业务层自定义命令（过滤内部事件后的）
    @objc optional func onIMRecvCustomCommand(_ fromUser: ZegoUIKitUser, command: String)
    
    /// 文本消息接收（兼容信令通道）
    @objc optional func onInRoomTextMessageReceived(_ messages: [ZegoSignalingInRoomTextMessage], roomID: String)
    
    /// 命令消息接收（兼容信令通道）
    @objc optional func onInRoomCommandMessageReceived(_ messages: [ZegoSignalingInRoomCommandMessage], roomID: String)
    
    /// 弹幕消息接收（高并发场景优化）
    @objc optional func onIMRecvBarrageMessage(_ roomID: String, messageList: [ZegoUIKitBarrageMessageInfo])
    
    // MARK: - user in room attributs 用户属性事件
    /// 房间成员离开（批量通知）
    @objc optional func onRoomMemberLeft(_ userIDList: [String]?, roomID: String)
    
    /// 自己被移出房间（管理员操作）
    @objc optional func onMeRemovedFromRoom()
    
    /// 收到开启摄像头请求（连麦场景）
    @objc optional func onTurnOnYourCameraRequest(_ fromUser: ZegoUIKitUser)
    
    /// 收到开启麦克风请求（连麦场景）
    @objc optional func onTurnOnYourMicrophoneRequest(_ fromUser: ZegoUIKitUser)
    
    
    // MARK: - signal plugin 信令插件事件
    /// 信令连接状态变化（建立/断开/重连）
    @objc optional func onSignalingPluginConnectionState(_ params: [String: AnyObject])
    
    /// IM房间状态变化（兼容旧版信令）
    @objc optional func onIMRoomStateChanged(_ state: Int, event: Int, roomID: String)
    
    /// 收到邀请（连麦/PK等场景）
    @objc optional func onInvitationReceived(_ inviter: ZegoUIKitUser, type: Int, data: String?)
    
    /// 邀请超时（未在指定时间内响应）
    @objc optional func onInvitationTimeout(_ inviter: ZegoUIKitUser, data: String?)
    
    /// 被邀请方响应超时（群邀场景）
    @objc optional func onInvitationResponseTimeout(_ invitees: [ZegoUIKitUser], data: String?)
    
    /// 邀请被接受（进入连麦状态）
    @objc optional func onInvitationAccepted(_ invitee: ZegoUIKitUser, data: String?)
    
    /// 邀请被拒绝（显示拒绝提示）
    @objc optional func onInvitationRefused(_ invitee: ZegoUIKitUser, data: String?)
    
    /// 邀请被取消（发起方撤回）
    @objc optional func onInvitationCanceled(_ inviter: ZegoUIKitUser, data: String?)
    
    /// 信令房间属性更新（单个键值）
    @objc optional func onSignalPluginRoomPropertyUpdated(_ key: String, oldValue: String, newValue: String)
    
    /// 信令房间全量属性更新
    @objc optional func onSignalPluginRoomPropertyFullUpdated(_ updateKeys: [String], oldProperties: [String : String], properties: [String : String])
    
    /// 用户属性批量更新（如角色变更、权限修改）
    @objc optional func onUsersInRoomAttributesUpdated(_ updateKeys: [String]?, oldAttributes: [ZegoUserInRoomAttributesInfo]?, attributes: [ZegoUserInRoomAttributesInfo]?, editor: ZegoUIKitUser?)
    
    
    // MARK: - 视频帧处理（高级功能）
    /// 接收远端视频帧（原始像素数据）
    /// - 典型应用: 自定义渲染、AI人脸识别
    /// - 参数buffer: 视频帧数据(CVPixelBuffer格式)
    /// - 参数param: 帧格式信息（分辨率/旋转等）
    @objc optional func onRemoteVideoFrameCVPixelBuffer(_ buffer: CVPixelBuffer, param: ZegoVideoFrameParam, streamID: String)
    
    /// 本地采集视频帧（美颜处理前）
    /// - 典型应用: 第三方美颜SDK接入
    /// - 参数flipMode: 镜像模式（预览需镜像）
    @objc optional func onCapturedVideoFrameCVPixelBuffer(_ buffer: CVPixelBuffer, param: ZegoVideoFrameParam, flipMode: ZegoVideoFlipMode, channel: ZegoPublishChannel)
    
}

